.\" $OpenBSD: CMS_get0_type.3,v 1.9 2023/07/27 05:31:28 tb Exp $
.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2008, 2015 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 27 2023 $
.Dt CMS_GET0_TYPE 3
.Os
.Sh NAME
.Nm CMS_get0_type ,
.Nm CMS_get_version ,
.Nm CMS_set1_eContentType ,
.Nm CMS_get0_eContentType ,
.Nm CMS_get0_content
.Nd get and set CMS content types and content
.Sh SYNOPSIS
.In openssl/cms.h
.Ft const ASN1_OBJECT *
.Fo CMS_get0_type
.Fa "const CMS_ContentInfo *cms"
.Fc
.Ft int
.Fo CMS_get_version
.Fa "const CMS_ContentInfo *cms"
.Fa "long *version"
.Fc
.Ft int
.Fo CMS_set1_eContentType
.Fa "CMS_ContentInfo *cms"
.Fa "const ASN1_OBJECT *oid"
.Fc
.Ft const ASN1_OBJECT *
.Fo CMS_get0_eContentType
.Fa "CMS_ContentInfo *cms"
.Fc
.Ft ASN1_OCTET_STRING **
.Fo CMS_get0_content
.Fa "CMS_ContentInfo *cms"
.Fc
.Sh DESCRIPTION
.Fn CMS_get0_type
returns the content type of the
.Vt ContentInfo
structure
.Fa cms .
The
.Vt ASN1_OBJECT
value returned can be converted to an integer NID value using
.Xr OBJ_obj2nid 3 .
The following content types are identified by the following NIDs:
.Pp
.Bl -column AuthenticatedData NID_id_smime_ct_compressedData -compact
.It Vt SignedData        Ta Dv NID_pkcs7_signed
.It Vt EnvelopedData     Ta Dv NID_pkcs7_enveloped
.It Vt DigestedData      Ta Dv NID_pkcs7_digest
.It Vt EncryptedData     Ta Dv NID_pkcs7_encrypted
.It Vt AuthenticatedData Ta Dv NID_id_smime_ct_authData
.It Vt CompressedData    Ta Dv NID_id_smime_ct_compressedData
.It arbitrary data       Ta Dv NID_pkcs7_data
.El
.Pp
The
.Vt SignedData ,
.Vt DigestedData ,
.Vt AuthenticatedData ,
and
.Vt CompressedData
types contain a field
.Fa encapContentInfo
to allow embedding content, and
.Vt EnvelopedData
and
.Vt EncryptedData
contain a field
.Fa encryptedContentInfo
for that purpose.
The type of the embedded content to be stored in that field can be
set with the function
.Fn CMS_set1_eContentType ,
to be called on
.Fa cms
structures returned from functions such as
.Xr CMS_sign 3
or
.Xr CMS_encrypt 3
with the
.Dv CMS_PARTIAL
flag set and
.Em before
the structure is finalised; otherwise the results are undefined.
.Fn CMS_set1_eContentType
copies the supplied
.Fa oid ,
so it should be freed up after use.
.Pp
.Fn CMS_get_version
sets
.Pf * Fa version
to the syntax version number of the
.Vt ContentInfo
structure
.Fa cms .
The version is a number between 0 and 5 and is defined for all the
above content types except for arbitrary data.
For arbitrary data and unsupported content types
.Fn CMS_get_version
fails and the content of
.Pf * Fa version
is unspecified.
.Pp
.Fn CMS_get0_eContentType
returns the type of the embedded content.
.Pp
.Fn CMS_get0_content
returns a pointer to the storage location where the pointer to the
embedded content is stored.
That means that for example after
.Pp
.Dl ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
.Pp
.Pf * Va pconf
could be
.Dv NULL
if there is no embedded content.
Applications can access, modify or create the embedded content in a
.Vt CMS_ContentInfo
structure using this function.
Applications usually will not need to modify the embedded content as it
is normally set by higher level functions.
.Sh RETURN VALUES
.Fn CMS_get0_type
and
.Fn CMS_get0_eContentType
return internal pointers to
.Vt OBJECT IDENTIFIER
structures.
.Pp
.Fn CMS_get_version
returns 1 on success and 0 on failure.
.Pp
.Fn CMS_get0_content
returns an internal pointer to the storage location where the pointer
to the embedded content is stored.
.Pp
.Fn CMS_set1_eContentType
returns 1 for success or 0 if an error occurred.
The error can be obtained from
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr CMS_ContentInfo_new 3 ,
.Xr d2i_CMS_ContentInfo 3 ,
.Xr SMIME_read_CMS 3
.Sh STANDARDS
RFC 5652: Cryptographic Message Syntax
.Pp
RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS)
.Sh HISTORY
These functions first appeared in OpenSSL 0.9.8h
and have been available since
.Ox 6.7 .
.Pp
.Fn CMS_get_version
first appeared in
.Ox 7.4 .
